<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org" />
<title>Introduction</title>
<meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79" />
<link rel="HOME" title="FreeBSD Handbook" href="index.html" />
<link rel="UP" title="Serial Communications" href="serialcomms.html" />
<link rel="PREVIOUS" title="Serial Communications" href="serialcomms.html" />
<link rel="NEXT" title="Terminals" href="term.html" />
<link rel="STYLESHEET" type="text/css" href="docbook.css" />
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
</head>
<body class="SECT1" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#840084"
alink="#0000FF">
<div class="NAVHEADER">
<table summary="Header navigation table" width="100%" border="0" cellpadding="0"
cellspacing="0">
<tr>
<th colspan="3" align="center">FreeBSD Handbook</th>
</tr>

<tr>
<td width="10%" align="left" valign="bottom"><a href="serialcomms.html"
accesskey="P">Prev</a></td>
<td width="80%" align="center" valign="bottom">Chapter 26 Serial Communications</td>
<td width="10%" align="right" valign="bottom"><a href="term.html"
accesskey="N">Next</a></td>
</tr>
</table>

<hr align="LEFT" width="100%" />
</div>

<div class="SECT1">
<h1 class="SECT1"><a id="SERIAL" name="SERIAL">26.2 Introduction</a></h1>

<div class="SECT2">
<h2 class="SECT2"><a id="SERIAL-TERMINOLOGY" name="SERIAL-TERMINOLOGY">26.2.1
Terminology</a></h2>

<div class="VARIABLELIST">
<dl>
<dt>bps</dt>

<dd>
<p>Bits per Second -- the rate at which data is transmitted</p>
</dd>

<dt>DTE</dt>

<dd>
<p>Data Terminal Equipment -- for example, your computer</p>
</dd>

<dt>DCE</dt>

<dd>
<p>Data Communications Equipment -- your modem</p>
</dd>

<dt>RS-232</dt>

<dd>
<p>EIA standard for hardware serial communications</p>
</dd>
</dl>
</div>

<p>When talking about communications data rates, this section does not use the term
&#8220;baud&#8221;. Baud refers to the number of electrical state transitions that may be
made in a period of time, while &#8220;bps&#8221; (bits per second) is the <span
class="emphasis"><i class="EMPHASIS">correct</i></span> term to use (at least it does not
seem to bother the curmudgeons quite as much).</p>
</div>

<div class="SECT2">
<h2 class="SECT2"><a id="SERIAL-CABLES-PORTS" name="SERIAL-CABLES-PORTS">26.2.2 Cables
and Ports</a></h2>

<p>To connect a modem or terminal to your FreeBSD system, you will need a serial port on
your computer and the proper cable to connect to your serial device. If you are already
familiar with your hardware and the cable it requires, you can safely skip this
section.</p>

<div class="SECT3">
<h3 class="SECT3"><a id="TERM-CABLES" name="TERM-CABLES">26.2.2.1 Cables</a></h3>

<p>There are several different kinds of serial cables. The two most common types for our
purposes are null-modem cables and standard (&#8220;straight&#8221;) RS-232 cables. The
documentation for your hardware should describe the type of cable required.</p>

<div class="SECT4">
<h4 class="SECT4"><a id="TERM-CABLES-NULL" name="TERM-CABLES-NULL">26.2.2.1.1 Null-modem
Cables</a></h4>

<p>A null-modem cable passes some signals, such as &#8220;Signal Ground&#8221;, straight
through, but switches other signals. For example, the &#8220;Transmitted Data&#8221; pin
on one end goes to the &#8220;Received Data&#8221; pin on the other end.</p>

<p>You can also construct your own null-modem cable for use with terminals (e.g., for
quality purposes). This table shows the RS-232C <a
href="dialup.html#SERIALCOMMS-SIGNAL-NAMES">signals</a> and the pin numbers on a DB-25
connector. Note that the standard also calls for a straight-through pin 1 to pin 1 <span
class="emphasis"><i class="EMPHASIS">Protective Ground</i></span> line, but it is often
omitted. Some terminals work OK using only pins 2, 3 and 7, while others require
different configurations than the examples shown below.</p>

<div class="TABLE"><a id="AEN31757" name="AEN31757"></a>
<p><b>Table 26-1. DB-25 to DB-25 Null-Modem Cable</b></p>

<table border="0" frame="void" width="100%" class="CALSTABLE">
<col />
<col />
<col />
<col />
<col />
<thead>
<tr>
<th align="LEFT">Signal</th>
<th align="LEFT">Pin #</th>
<th>&nbsp;</th>
<th align="LEFT">Pin #</th>
<th align="LEFT">Signal</th>
</tr>
</thead>

<tbody>
<tr>
<td>SG</td>
<td>7</td>
<td>connects to</td>
<td>7</td>
<td>SG</td>
</tr>

<tr>
<td>TD</td>
<td>2</td>
<td>connects to</td>
<td>3</td>
<td>RD</td>
</tr>

<tr>
<td>RD</td>
<td>3</td>
<td>connects to</td>
<td>2</td>
<td>TD</td>
</tr>

<tr>
<td>RTS</td>
<td>4</td>
<td>connects to</td>
<td>5</td>
<td>CTS</td>
</tr>

<tr>
<td>CTS</td>
<td>5</td>
<td>connects to</td>
<td>4</td>
<td>RTS</td>
</tr>

<tr>
<td>DTR</td>
<td>20</td>
<td>connects to</td>
<td>6</td>
<td>DSR</td>
</tr>

<tr>
<td>DTR</td>
<td>20</td>
<td>connects to</td>
<td>8</td>
<td>DCD</td>
</tr>

<tr>
<td>DSR</td>
<td>6</td>
<td>connects to</td>
<td>20</td>
<td>DTR</td>
</tr>

<tr>
<td>DCD</td>
<td>8</td>
<td>connects to</td>
<td>20</td>
<td>DTR</td>
</tr>
</tbody>
</table>
</div>

<p>Here are two other schemes more common nowadays.</p>

<div class="TABLE"><a id="AEN31823" name="AEN31823"></a>
<p><b>Table 26-2. DB-9 to DB-9 Null-Modem Cable</b></p>

<table border="0" frame="void" width="100%" class="CALSTABLE">
<col />
<col />
<col />
<col />
<col />
<thead>
<tr>
<th align="LEFT">Signal</th>
<th align="LEFT">Pin #</th>
<th>&nbsp;</th>
<th align="LEFT">Pin #</th>
<th align="LEFT">Signal</th>
</tr>
</thead>

<tbody>
<tr>
<td>RD</td>
<td>2</td>
<td>connects to</td>
<td>3</td>
<td>TD</td>
</tr>

<tr>
<td>TD</td>
<td>3</td>
<td>connects to</td>
<td>2</td>
<td>RD</td>
</tr>

<tr>
<td>DTR</td>
<td>4</td>
<td>connects to</td>
<td>6</td>
<td>DSR</td>
</tr>

<tr>
<td>DTR</td>
<td>4</td>
<td>connects to</td>
<td>1</td>
<td>DCD</td>
</tr>

<tr>
<td>SG</td>
<td>5</td>
<td>connects to</td>
<td>5</td>
<td>SG</td>
</tr>

<tr>
<td>DSR</td>
<td>6</td>
<td>connects to</td>
<td>4</td>
<td>DTR</td>
</tr>

<tr>
<td>DCD</td>
<td>1</td>
<td>connects to</td>
<td>4</td>
<td>DTR</td>
</tr>

<tr>
<td>RTS</td>
<td>7</td>
<td>connects to</td>
<td>8</td>
<td>CTS</td>
</tr>

<tr>
<td>CTS</td>
<td>8</td>
<td>connects to</td>
<td>7</td>
<td>RTS</td>
</tr>
</tbody>
</table>
</div>

<div class="TABLE"><a id="AEN31888" name="AEN31888"></a>
<p><b>Table 26-3. DB-9 to DB-25 Null-Modem Cable</b></p>

<table border="0" frame="void" width="100%" class="CALSTABLE">
<col />
<col />
<col />
<col />
<col />
<thead>
<tr>
<th align="LEFT">Signal</th>
<th align="LEFT">Pin #</th>
<th>&nbsp;</th>
<th align="LEFT">Pin #</th>
<th align="LEFT">Signal</th>
</tr>
</thead>

<tbody>
<tr>
<td>RD</td>
<td>2</td>
<td>connects to</td>
<td>2</td>
<td>TD</td>
</tr>

<tr>
<td>TD</td>
<td>3</td>
<td>connects to</td>
<td>3</td>
<td>RD</td>
</tr>

<tr>
<td>DTR</td>
<td>4</td>
<td>connects to</td>
<td>6</td>
<td>DSR</td>
</tr>

<tr>
<td>DTR</td>
<td>4</td>
<td>connects to</td>
<td>8</td>
<td>DCD</td>
</tr>

<tr>
<td>SG</td>
<td>5</td>
<td>connects to</td>
<td>7</td>
<td>SG</td>
</tr>

<tr>
<td>DSR</td>
<td>6</td>
<td>connects to</td>
<td>20</td>
<td>DTR</td>
</tr>

<tr>
<td>DCD</td>
<td>1</td>
<td>connects to</td>
<td>20</td>
<td>DTR</td>
</tr>

<tr>
<td>RTS</td>
<td>7</td>
<td>connects to</td>
<td>5</td>
<td>CTS</td>
</tr>

<tr>
<td>CTS</td>
<td>8</td>
<td>connects to</td>
<td>4</td>
<td>RTS</td>
</tr>
</tbody>
</table>
</div>

<div class="NOTE">
<blockquote class="NOTE">
<p><b>Note:</b> When one pin at one end connects to a pair of pins at the other end, it
is usually implemented with one short wire between the pair of pins in their connector
and a long wire to the other single pin.</p>
</blockquote>
</div>

<p>The above designs seems to be the most popular. In another variation (explained in the
book <span class="emphasis"><i class="EMPHASIS">RS-232 Made Easy</i></span>) SG connects
to SG, TD connects to RD, RTS and CTS connect to DCD, DTR connects to DSR, and
vice-versa.</p>
</div>

<div class="SECT4">
<h4 class="SECT4"><a id="TERM-CABLES-STD" name="TERM-CABLES-STD">26.2.2.1.2 Standard
RS-232C Cables</a></h4>

<p>A standard serial cable passes all of the RS-232C signals straight through. That is,
the &#8220;Transmitted Data&#8221; pin on one end of the cable goes to the
&#8220;Transmitted Data&#8221; pin on the other end. This is the type of cable to use to
connect a modem to your FreeBSD system, and is also appropriate for some terminals.</p>
</div>
</div>

<div class="SECT3">
<h3 class="SECT3"><a id="TERM-PORTS" name="TERM-PORTS">26.2.2.2 Ports</a></h3>

<p>Serial ports are the devices through which data is transferred between the FreeBSD
host computer and the terminal. This section describes the kinds of ports that exist and
how they are addressed in FreeBSD.</p>

<div class="SECT4">
<h4 class="SECT4"><a id="TERM-PORTKINDS" name="TERM-PORTKINDS">26.2.2.2.1 Kinds of
Ports</a></h4>

<p>Several kinds of serial ports exist. Before you purchase or construct a cable, you
need to make sure it will fit the ports on your terminal and on the FreeBSD system.</p>

<p>Most terminals will have DB-25 ports. Personal computers, including PCs running
FreeBSD, will have DB-25 or DB-9 ports. If you have a multiport serial card for your PC,
you may have RJ-12 or RJ-45 ports.</p>

<p>See the documentation that accompanied the hardware for specifications on the kind of
port in use. A visual inspection of the port often works too.</p>
</div>


<div class="SECT4">
<h4 class="SECT4"><a id="TERM-PORTNAMES" name="TERM-PORTNAMES">26.2.2.2.2 Port
Names</a></h4>


<p>In FreeBSD, you access each serial port through an entry in the <tt
class="FILENAME">/dev</tt> directory. There are two different kinds of entries:</p>

<ul>
<li>
<p>Call-in ports are named <tt class="FILENAME">/dev/ttyd<tt
class="REPLACEABLE"><i>N</i></tt></tt> where <tt class="REPLACEABLE"><i>N</i></tt> is the
port number, starting from zero. Generally, you use the call-in port for terminals.
Call-in ports require that the serial line assert the data carrier detect (DCD) signal to
work correctly.</p>
</li>


<li>
<p>Call-out ports are named <tt class="FILENAME">/dev/cuad<tt
class="REPLACEABLE"><i>N</i></tt></tt>. You usually do not use the call-out port for
terminals, just for modems. You may use the call-out port if the serial cable or the
terminal does not support the carrier detect signal.</p>
</li>
</ul>

<p>If you have connected a terminal to the first serial port (<tt
class="DEVICENAME">COM1</tt> in <span class="TRADEMARK">MS-DOS</span>&reg;), then you
will use <tt class="FILENAME">/dev/ttyd0</tt> to refer to the terminal. If the terminal
is on the second serial port (also known as <tt class="DEVICENAME">COM2</tt>), use <tt
class="FILENAME">/dev/ttyd1</tt>, and so forth.</p>
</div>
</div>
</div>

<div class="SECT2">
<h2 class="SECT2"><a id="AEN31992" name="AEN31992">26.2.3 Kernel Configuration</a></h2>

<p>FreeBSD supports four serial ports by default. In the <span
class="TRADEMARK">MS-DOS</span> world, these are known as <tt
class="DEVICENAME">COM1</tt>, <tt class="DEVICENAME">COM2</tt>, <tt
class="DEVICENAME">COM3</tt>, and <tt class="DEVICENAME">COM4</tt>. FreeBSD currently
supports &#8220;dumb&#8221; multiport serial interface cards, such as the BocaBoard 1008
and 2016, as well as more intelligent multi-port cards such as those made by Digiboard
and Stallion Technologies. However, the default kernel only looks for the standard COM
ports.</p>

<p>To see if your kernel recognizes any of your serial ports, watch for messages while
the kernel is booting, or use the <tt class="COMMAND">/sbin/dmesg</tt> command to replay
the kernel's boot messages. In particular, look for messages that start with the
characters <tt class="LITERAL">sio</tt>.</p>

<div class="TIP">
<blockquote class="TIP">
<p><b>Tip:</b> To view just the messages that have the word <tt class="LITERAL">sio</tt>,
use the command:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">/sbin/dmesg | grep 'sio'</kbd>
</pre>
</blockquote>
</div>

<p>For example, on a system with four serial ports, these are the serial-port specific
kernel boot messages:</p>

<pre class="SCREEN">
sio0 at 0x3f8-0x3ff irq 4 on isa
sio0: type 16550A
sio1 at 0x2f8-0x2ff irq 3 on isa
sio1: type 16550A
sio2 at 0x3e8-0x3ef irq 5 on isa
sio2: type 16550A
sio3 at 0x2e8-0x2ef irq 9 on isa
sio3: type 16550A
</pre>

<p>If your kernel does not recognize all of your serial ports, you will probably need to
configure your kernel in the <tt class="FILENAME">/boot/device.hints</tt> file. You can
also comment-out or completely remove lines for devices you do not have.</p>

<p>Please refer to the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=sio&amp;sektion=4"><span
class="CITEREFENTRY"><span class="REFENTRYTITLE">sio</span>(4)</span></a> manual page for
more information on serial ports and multiport boards configuration. Be careful if you
are using a configuration file that was previously used for a different version of
FreeBSD because the device flags and the syntax have changed between versions.</p>

<div class="NOTE">
<blockquote class="NOTE">
<p><b>Note:</b> <tt class="LITERAL">port IO_COM1</tt> is a substitution for <tt
class="LITERAL">port 0x3f8</tt>, <tt class="LITERAL">IO_COM2</tt> is <tt
class="LITERAL">0x2f8</tt>, <tt class="LITERAL">IO_COM3</tt> is <tt
class="LITERAL">0x3e8</tt>, and <tt class="LITERAL">IO_COM4</tt> is <tt
class="LITERAL">0x2e8</tt>, which are fairly common port addresses for their respective
serial ports; interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. Also
note that regular serial ports <span class="emphasis"><i
class="EMPHASIS">cannot</i></span> share interrupts on ISA-bus PCs (multiport boards have
on-board electronics that allow all the 16550A's on the board to share one or two
interrupt request lines).</p>
</blockquote>
</div>
</div>

<div class="SECT2">
<h2 class="SECT2"><a id="AEN32029" name="AEN32029">26.2.4 Device Special Files</a></h2>

<p>Most devices in the kernel are accessed through &#8220;device special files&#8221;,
which are located in the <tt class="FILENAME">/dev</tt> directory. The <tt
class="DEVICENAME">sio</tt> devices are accessed through the <tt
class="FILENAME">/dev/ttyd<tt class="REPLACEABLE"><i>N</i></tt></tt> (dial-in) and <tt
class="FILENAME">/dev/cuad<tt class="REPLACEABLE"><i>N</i></tt></tt> (call-out) devices.
FreeBSD also provides initialization devices (<tt class="FILENAME">/dev/ttyd<tt
class="REPLACEABLE"><i>N</i></tt>.init</tt> and <tt class="FILENAME">/dev/cuad<tt
class="REPLACEABLE"><i>N</i></tt>.init</tt>) and locking devices (<tt
class="FILENAME">/dev/ttyd<tt class="REPLACEABLE"><i>N</i></tt>.lock</tt> and <tt
class="FILENAME">/dev/cuad<tt class="REPLACEABLE"><i>N</i></tt>.lock</tt>). The
initialization devices are used to initialize communications port parameters each time a
port is opened, such as <tt class="LITERAL">crtscts</tt> for modems which use <tt
class="LITERAL">RTS/CTS</tt> signaling for flow control. The locking devices are used to
lock flags on ports to prevent users or programs changing certain parameters; see the
manual pages <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=termios&amp;sektion=4"><span
class="CITEREFENTRY"><span class="REFENTRYTITLE">termios</span>(4)</span></a>, <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=sio&amp;sektion=4"><span
class="CITEREFENTRY"><span class="REFENTRYTITLE">sio</span>(4)</span></a>, and <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=stty&amp;sektion=1"><span
class="CITEREFENTRY"><span class="REFENTRYTITLE">stty</span>(1)</span></a> for
information on the terminal settings, locking and initializing devices, and setting
terminal options, respectively.</p>
</div>

<div class="SECT2">
<h2 class="SECT2"><a id="SERIAL-HW-CONFIG" name="SERIAL-HW-CONFIG">26.2.5 Serial Port
Configuration</a></h2>

<p>The <tt class="DEVICENAME">ttyd<tt class="REPLACEABLE"><i>N</i></tt></tt> (or <tt
class="DEVICENAME">cuad<tt class="REPLACEABLE"><i>N</i></tt></tt>) device is the regular
device you will want to open for your applications. When a process opens the device, it
will have a default set of terminal I/O settings. You can see these settings with the
command</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">stty -a -f /dev/ttyd1</kbd>
</pre>

<p>When you change the settings to this device, the settings are in effect until the
device is closed. When it is reopened, it goes back to the default set. To make changes
to the default set, you can open and adjust the settings of the &#8220;initial
state&#8221; device. For example, to turn on <code class="OPTION">CLOCAL</code> mode, 8
bit communication, and <code class="OPTION">XON/XOFF</code> flow control by default for
<tt class="DEVICENAME">ttyd5</tt>, type:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd
class="USERINPUT">stty -f /dev/ttyd5.init clocal cs8 ixon ixoff</kbd>
</pre>

<p>System-wide initialization of the serial devices is controlled in <tt
class="FILENAME">/etc/rc.d/serial</tt>. This file affects the default settings of serial
devices.</p>

<p>To prevent certain settings from being changed by an application, make adjustments to
the &#8220;lock state&#8221; device. For example, to lock the speed of <tt
class="DEVICENAME">ttyd5</tt> to 57600&nbsp;bps, type:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">stty -f /dev/ttyd5.lock 57600</kbd>
</pre>

<p>Now, an application that opens <tt class="DEVICENAME">ttyd5</tt> and tries to change
the speed of the port will be stuck with 57600&nbsp;bps.</p>

<p>Naturally, you should make the initial state and lock state devices writable only by
the <tt class="USERNAME">root</tt> account.</p>
</div>
</div>

<div class="NAVFOOTER">
<hr align="LEFT" width="100%" />
<table summary="Footer navigation table" width="100%" border="0" cellpadding="0"
cellspacing="0">
<tr>
<td width="33%" align="left" valign="top"><a href="serialcomms.html"
accesskey="P">Prev</a></td>
<td width="34%" align="center" valign="top"><a href="index.html"
accesskey="H">Home</a></td>
<td width="33%" align="right" valign="top"><a href="term.html"
accesskey="N">Next</a></td>
</tr>

<tr>
<td width="33%" align="left" valign="top">Serial Communications</td>
<td width="34%" align="center" valign="top"><a href="serialcomms.html"
accesskey="U">Up</a></td>
<td width="33%" align="right" valign="top">Terminals</td>
</tr>
</table>
</div>

<p align="center"><small>This, and other documents, can be downloaded from <a
href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/</a>.</small></p>

<p align="center"><small>For questions about FreeBSD, read the <a
href="http://www.FreeBSD.org/docs.html">documentation</a> before contacting &#60;<a
href="mailto:questions@FreeBSD.org">questions@FreeBSD.org</a>&#62;.<br />
For questions about this documentation, e-mail &#60;<a
href="mailto:doc@FreeBSD.org">doc@FreeBSD.org</a>&#62;.</small></p>
</body>
</html>

